ASCII text
Formatting messages
Formatting in 30 seconds
To format messages you use special syntax.
*italic*or_italic_becomes italic.**bold**or__bold__becomes bold.~~strikethrough~~becomesstrikethrough.++inserted++becomes inserted.--deleted--becomesdeleted.[link](https://wikipedia.org)becomes link.becomes
.
`code`becomescode.Paragraphs are separated by a blank line.
~~~or~~~languagestarts a code block;~~~ends it.#starts a heading. The number of#s determines the level.>starts a blockquote.*or<number>.starts a list item.;makes a comment.A backslash at the end of a line forces a line break.
Introduction
The roundabout uses a markdown-like syntax to format messages, including commit messages, comments, descriptions, files and so on.
It is designed to be similar in philosophy to markdown, and for markdown users it should be really similar (this is why we use Markdown's extension and mime types provisionally, until there is more adoption).
Currently not all markdown (as described in Gruber's initial release) features are supported, but the most common use cases should be covered. Conversely, some extra features are available, primarily ones useful in a code review environment. Some special cases are handled differently compared to Gruber's markdown.
Very importantly, it is not CommonMark compliant!
There is also not a formalised specification for the syntax; first we need to stabilise it.
The syntax does not specify a particular output format, but the reference implementation shipped here outputs HTML.
Philosophy
Like the original markdown, the goal with this syntax is to make it possible to writeplain text that has formatting as a bonus when it's supported.
A document should be readable and publishable even if a rendered version is not available, in its raw form, without looking like it's been marked up with tags or formatting instructions.
Easy to read: The syntax should be understandable enough so that it is readable without rendering it, even for someone not familiar with this syntax.
Easy to write: The syntax should be easy to write using a regular keyboard, only in plain text. The renderer will try its best to understand the human.
However, it should be still easy to read. The syntax should look like what it represents, even if it's a little harder to write it.
Predictable: Edge-cases should be avoided as much as possible, as long as it still understands the writer's intent.
Easy (and fast) to render: A reasonably fast renderer should be possible to write with a reasonable amount of effort and a few lines of code in a high-level language.
Unambiguous: There should not be confusion in parsing. Precedence should be clear, and it should always prioritise the most likely interpretation.
Extensible: Without breaking forward compatibility, it should be possible to add new features to the syntax programmatically, including special interest features like charts, sheet music, or code review features.
Semantic: Available features should never imply altering the document's presentation, but rather its structure and meaning. Clients could style all features as they wish, as long as they reasonably make sense. Allowing the user to add stylesheets is fine, as long as the document itself doesn't contain any style information, and they're not mandatory.
Secure: The syntax should not allow for arbitrary code execution, or any other security risk. It should be safe to render untrusted documents.
Familiar and traditional: Users should be able to learn it in a few minutes, it should be similar to markdown, and follow traditions rooted in plain text mediums, such as email, Usenet, IRC or typewriters.
Structure and terminology
A document is a sequence ofblocks_. Many blocks, but not all, can contain other _child blocks too. Most blocks can hold content, in which case they can also hold _inline elements_.
Most inline elements can hold other inlines as well, but they can't hold blocks.
Some elements, both blocks and inlines, can have _attributes_. Generally this is specified in a clear way in the syntax.
Any sequence of characters is a valid document.
Blocks
Void
A void is just a blank line (appears white, i.e. is empty or only has spaces). It is used to force block separation and is not output in the rendered document.
block 1 block 2
turns into
block 1
block 2
Comment
If a line starts with ;, it is turned into a void, to allow the writer to
add comments to the document. This is not output in the rendered document,
like any other void. It also separates blocks.
block 1 ; this is a comment block 2
turns into
block 1
block 2
Plain text mediums haven't got a tradition of leaving comments. But the
character ; was used as it is very unlikely to appear at the start of a
line.
The space is not required. The line just has to begin with a semicolon.
Paragraph
Anything not recognised as another block is considered a paragraph. You can use voids to separate paragraphs. Within a paragraph, whitespace is collapsed like in HTML, so any sequence of spaces will become one space, and newlines will be ignored, although the rendered output can automatically wrap lines.
To force a line break in a paragraph, end the line with a backslash.
Important:\ Unlike in standard markdown, two trailing spaces do not force a line break. That syntax is often considered confusing: in most editors, trailing spaces are invisible.
Instead, use a backslash at the end of the line.
This is a paragraph. This is a new line in the same paragraph. It doesn't wrap, unless you force it to.\ Now it wraps. This is a new paragraph.
turns into
This is a paragraph. This is a new line in the same paragraph. It doesn't wrap, unless you force it to.\ Now it wraps.
This is a new paragraph.
Paragraphs can't contain other blocks because it wouldn't make sense, but they can contain inline elements.
When a block that can contain other blocks has plain text, it is automatically a paragraph, since the parsing is recursive.
Heading
ATX-style heading
ATX-style headings are lines which start with one or more #, then a space.
The number of #s determines the heading level.
For H1 you would use
#.For H2 you would use
##.For H3 you would use
###.For H4 you would use
####.For H5 you would use
#####.For H6 you would use
######.
# Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6
turns into
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Important:\ Unlike in standard markdown, a space after the
#is required. This is because it is more readable and less likely to convert unintended sequences of#s into headings. Additionally, markdown had a rarely-used feature that allowed closing headers with#s, which is not supported here.
Setext-style heading
Setext headings are only available for H1 and H2. To create an H1,
underline it with =, and to create an H2, underline it with -.
Heading 1 ========= Heading 2 ---------
turns into
Heading 1
Heading 2
The number of underlines doesn't matter; you can even use just one. However, it looks nicer if you match the width of the heading. I personally prefer this style where available as it gives more visual weight to the heading and matches traditions.
All headings are single-line. Headings cannot contain other blocks, but they can contain inline elements.
Fence (code block)
A fence is a block that starts and ends with either ```
or ~~~. Generally it is used for program code.
After the opening fence, on the same line, there can be a language descriptor. Usually it is used to apply syntax highlighting to the code inside, but it could be used for other purposes.
turns into ```text This is a code block.
The language descriptor is optional. If it is not present, the renderer should not apply syntax highlighting, and the block is assumed to be plain text.
Obviously, since the fence contains text that should be rendered specially, it can't contain any other blocks or inlines.
Indented code blocks are currently not supported, but they might be in the future.
Blockquote
A blockquote is a block that starts with >. It is used to quote
other text, or to set aside text that is not part of the main
content.
A space after the > is not required, but recommended for
readability.
Blockquotes can contain other blocks, but not inlines. If you want inlines they will be in a paragraph anyways.
> This is a blockquote. > It can contain multiple lines. > ## And even other blocks. > > And they can be nested. > And you can be lazy. > > If this isn't what you want, it can have voids too.
turns into
This is a blockquote. It can contain multiple lines.
And even other blocks.
And they can be nested. And you can be lazy.
If this isn't what you want, it can have voids too.
List
A list is a sequence of list items. List items are represented by lines
that start with *, +, or -, followed by a space, or with a number
followed by a period. The first type creates a bullet (unordered) list,
and the second type creates a numbered (ordered) list. For ordered lists,
the number doesn't matter; it always begins from 1 in HTML.
List items can contain other blocks.
A list item can have continuation lines and contain multiple blocks. Continuation lines are indented with _two spaces_.
Important:\ Unlike in standard markdown, a space after the
*,+or-is required. Also unlike in standard markdown, parsing works normally inside list items, but they must be indented with two spaces, not four. This is because it looks nicer with unordered lists:* This is a list item. This is a continuation line. ; this version vs. * This is a list item. This is a continuation line. ; real markdown
Horizontal rule
A horizontal rule is a line that contains only hyphens, underscores, or asterisks, and optionally spaces. The length must be at least 3.
---------------
________
* * *
turns into
Summary of blocks
Void: blank line, or line starting with
;, empty and not output.Paragraph: anything not recognised as another block, can contain
Heading: prefix with
#or underline, single-line, can containFence: code block, starts and ends with
~~~or```,Blockquote: starts with
>, can contain other blocks with recursiveList: starts with
*,+,-, or<number>., continuation linesHorizontal rule: line with at least 3 characters, hyphens,
Inline elements
Text
Technically not an inline element, represented by a simple text in the output. Anything not otherwise recognised is text.
Emphasis
Emphasis is represented by * or _ surrounding the text. When using _,
the emphasis must be surrounded by spaces or start/end of the line.
There can be at most 7 markers on each side, the number of opening markers must be exactly the same as the number of closing markers, and they cannot be mixed, unlike in standard markdown. (Maybe this will change in the future, but we'll see.) However mixing them sometimes works, only when nesting makes sense.
The number of markers is interpreted as a sum of powers of 2. If it's 4 or more then there's the third level of emphasis, if the remainder is 2 or more then there's the second level of emphasis, and if there's a remainder then there's the first level of emphasis. You can see how they look below:
level 1
level 2
level 1+2
level 3
level 1+3
level 2+3
level 1+2+3
Strikethrough
Strikethrough is represented by ~~ surrounding the text.
Diff marker
Diff markers are represented by ++ on either side of the text for inserted
text and -- for deleted text.
Link
Links are represented by [text](url). The text can contain inline elements.
Title attributes are currently not supported, but they will be.
Image
Images are represented by .
Code
Code is represented by ` surrounding the text.
Using two backticks is not currently supported.
Summary of inline elements
Text: anything not recognised as another inline element.
Emphasis:
*or_surrounding the text, at most 7 markers on each side.Strikethrough:
~~surrounding the text.Diff marker:
++or--surrounding the text.Link:
[text](url), text can contain inline elements.Image:
.Code:
`surrounding the text.
1
Formatting messages
2
===================
3
Formatting in 30 seconds
5
------------------------
6
To format messages you use special syntax.
8
* `*italic*` or `_italic_` becomes *italic*.
10
* `**bold**` or `__bold__` becomes **bold**.
11
* `~~strikethrough~~` becomes ~~strikethrough~~.
12
* `++inserted++` becomes ++inserted++.
13
* `--deleted--` becomes --deleted--.
14
* `[link](https://wikipedia.org)` becomes [link](https://wikipedia.org).
15
* ``
16
becomes .
17
* ``code`` becomes `code`.
18
* Paragraphs are separated by a blank line.
19
* `~~~` or `~~~language` starts a code block; `~~~` ends it.
20
* `#` starts a heading. The number of `#`s determines the level.
21
* `>` starts a blockquote.
22
* `*` or `<number>. ` starts a list item.
23
* `;` makes a comment.
24
* A backslash at the end of a line forces a line break.
25
Introduction
27
------------
28
The roundabout uses a markdown-like syntax to format messages, including
30
commit messages, comments, descriptions, files and so on.
31
It is designed to be similar in philosophy to markdown, and for markdown
33
users it should be really similar (this is why we use Markdown's extension
34
and mime types provisionally, until there is more adoption).
35
Currently not all markdown (as described in Gruber's initial release)
37
features are supported, but the most common use cases should be covered.
38
Conversely, some extra features are available, primarily ones useful in
39
a code review environment. Some special cases are handled differently
40
compared to Gruber's markdown.
41
Very importantly, it is *******not******* CommonMark compliant!
43
There is also not a formalised specification for the syntax; first we need
45
to stabilise it.
46
The syntax does not specify a particular output format, but the reference
48
implementation shipped here outputs HTML.
49
Philosophy
51
----------
52
Like the original markdown, the goal with this syntax is to make it possible
54
to write _plain_ text that has formatting as a bonus when it's supported.
55
A document should be readable and publishable even if a rendered version is
57
not available, in its raw form, without looking like it's been marked up
58
with tags or formatting instructions.
59
* **Easy to read:** The syntax should be understandable enough
61
so that it is readable without rendering it, even for someone not familiar
62
with this syntax.
63
* **Easy to write:** The syntax should be easy to write using a
64
regular keyboard, only in plain text. The renderer will try its best to
65
understand the human.
66
* However, it should be still easy to read. The syntax should look like
67
what it represents, even if it's a little harder to write it.
68
* **Predictable:** Edge-cases should be avoided as much as
69
possible, as long as it still understands the writer's intent.
70
* **Easy (and fast) to render:** A reasonably fast renderer should
71
be possible to write with a reasonable amount of effort and a few lines of
72
code in a high-level language.
73
* **Unambiguous:** There should not be confusion in parsing.
74
Precedence should be clear, and it should always prioritise the most likely
75
interpretation.
76
* **Extensible:** Without breaking forward compatibility, it should
77
be possible to add new features to the syntax programmatically, including
78
special interest features like charts, sheet music, or code review features.
79
* **Semantic:** Available features should never imply altering
80
the document's presentation, but rather its structure and meaning. Clients
81
could style all features as they wish, as long as they reasonably make sense.
82
Allowing the user to add stylesheets is fine, as long as the document itself
83
doesn't contain any style information, and they're not mandatory.
84
* **Secure:** The syntax should not allow for arbitrary code execution, or any
85
other security risk. It should be safe to render untrusted documents.
86
* **Familiar and traditional**: Users should be able to learn it in a few minutes,
87
it should be similar to markdown, and follow traditions rooted in plain text
88
mediums, such as email, Usenet, IRC or typewriters.
89
Structure and terminology
91
-------------------------
92
A document is a sequence of _blocks_. Many blocks, but not all, can contain other
94
_child_ blocks too. Most blocks can hold content, in which case they can also hold
95
_inline elements_.
96
Most inline elements can hold other inlines as well, but they can't hold blocks.
98
Some elements, both blocks and inlines, can have _attributes_. Generally this is
100
specified in a clear way in the syntax.
101
Any sequence of characters is a valid document.
103
Blocks
105
------
106
### Void
108
A void is just a blank line (appears white, i.e. is empty or only has spaces).
109
It is used to force block separation and is not output in the rendered document.
110
~~~
112
block 1
113
block 2
115
~~~
116
turns into
118
block 1
120
block 2
122
#### Comment
124
If a line starts with `;`, it is turned into a void, to allow the writer to
125
add comments to the document. This is not output in the rendered document,
126
like any other void. It also separates blocks.
127
~~~
129
block 1
130
; this is a comment
131
block 2
132
~~~
133
turns into
135
block 1
137
; this is a comment
138
block 2
139
Plain text mediums haven't got a tradition of leaving comments. But the
141
character `;` was used as it is very unlikely to appear at the start of a
142
line.
143
The space is not required. The line just has to begin with a semicolon.
145
### Paragraph
147
Anything not recognised as another block is considered a paragraph. You can
148
use voids to separate paragraphs. Within a paragraph, whitespace is collapsed
149
like in HTML, so any sequence of spaces will become one space, and newlines
150
will be ignored, although the rendered output can automatically wrap lines.
151
To force a line break in a paragraph, end the line with a backslash.
153
> **Important:**\
155
> Unlike in standard markdown, two trailing spaces do not force a line break.
156
> That syntax is often considered confusing: in most editors, trailing spaces
157
> are invisible.
158
>
159
> Instead, use a backslash at the end of the line.
160
~~~
162
This is a paragraph.
163
This is a new line in the same paragraph.
164
It doesn't wrap, unless you force it to.\
165
Now it wraps.
166
This is a new paragraph.
168
~~~
169
turns into
171
This is a paragraph.
173
This is a new line in the same paragraph.
174
It doesn't wrap, unless you force it to.\
175
Now it wraps.
176
This is a new paragraph.
178
Paragraphs can't contain other blocks because it wouldn't make sense, but
180
they can contain inline elements.
181
When a block that can contain other blocks has plain text, it is
183
automatically a paragraph, since the parsing is recursive.
184
### Heading
186
#### ATX-style heading
187
ATX-style headings are lines which start with one or more `#`, then a space.
188
The number of `#`s determines the heading level.
189
* For H1 you would use `#`.
191
* For H2 you would use `##`.
192
* For H3 you would use `###`.
193
* For H4 you would use `####`.
194
* For H5 you would use `#####`.
195
* For H6 you would use `######`.
196
~~~
198
# Heading 1
199
## Heading 2
200
### Heading 3
201
#### Heading 4
202
##### Heading 5
203
###### Heading 6
204
~~~
205
turns into
207
# Heading 1
209
## Heading 2
210
### Heading 3
211
#### Heading 4
212
##### Heading 5
213
###### Heading 6
214
> **Important:**\
216
> Unlike in standard markdown, a space after the `#` is required.
217
> This is because it is more readable and less likely to convert
218
> unintended sequences of `#`s into headings.
219
> Additionally, markdown had a rarely-used feature that allowed
220
> closing headers with `#`s, which is not supported here.
221
#### Setext-style heading
223
Setext headings are only available for H1 and H2. To create an H1,
224
underline it with `=`, and to create an H2, underline it with `-`.
225
~~~
227
Heading 1
228
=========
229
Heading 2
231
---------
232
~~~
233
turns into
235
Heading 1
237
=========
238
Heading 2
240
---------
241
The number of underlines doesn't matter; you can even use just one.
243
However, it looks nicer if you match the width of the heading.
244
I personally prefer this style where available as it gives more visual
245
weight to the heading and matches traditions.
246
All headings are single-line. Headings cannot contain other blocks,
248
but they can contain inline elements.
249
### Fence (code block)
251
A fence is a block that starts and ends with either `````
252
or `~~~`. Generally it is used for program code.
253
After the opening fence, on the same line, there can be a language
255
descriptor. Usually it is used to apply syntax highlighting to the
256
code inside, but it could be used for other purposes.
257
~~~
259
```text
260
This is a code block.
261
```
262
~~~
263
turns into
265
```text
267
This is a code block.
268
```
269
The language descriptor is optional. If it is not present, the
271
renderer should not apply syntax highlighting, and the block is
272
assumed to be plain text.
273
Obviously, since the fence contains text that should be rendered
275
specially, it can't contain any other blocks or inlines.
276
Indented code blocks are currently not supported, but they might
278
be in the future.
279
### Blockquote
281
A blockquote is a block that starts with `>`. It is used to quote
282
other text, or to set aside text that is not part of the main
283
content.
284
A space after the `>` is not required, but recommended for
286
readability.
287
Blockquotes can contain other blocks, but not inlines. If you want
289
inlines they will be in a paragraph anyways.
290
~~~
292
> This is a blockquote.
293
> It can contain multiple lines.
294
> ## And even other blocks.
295
> > And they can be nested.
296
> And you can be lazy.
297
>
298
> If this isn't what you want, it can have voids too.
299
~~~
300
turns into
302
> This is a blockquote.
304
> It can contain multiple lines.
305
> ## And even other blocks.
306
> > And they can be nested.
307
> And you can be lazy.
308
>
309
> If this isn't what you want, it can have voids too.
310
### List
312
A list is a sequence of list items. List items are represented by lines
313
that start with `*`, `+`, or `-`, followed by a space, or with a number
314
followed by a period. The first type creates a bullet (unordered) list,
315
and the second type creates a numbered (ordered) list. For ordered lists,
316
the number doesn't matter; it always begins from 1 in HTML.
317
List items can contain other blocks.
319
A list item can have continuation lines and contain multiple blocks.
321
Continuation lines are indented with _two spaces_.
322
> **Important:**\
324
> Unlike in standard markdown, a space after the `*`, `+` or `-` is
325
> required.
326
> Also unlike in standard markdown, parsing works normally inside
327
> list items, but they must be indented with two spaces, not four.
328
> This is because it looks nicer with unordered lists:
329
> ~~~
330
> * This is a list item.
331
> This is a continuation line.
332
> ; this version vs.
333
> * This is a list item.
334
> This is a continuation line.
335
> ; real markdown
336
> ~~~
337
### Horizontal rule
339
A horizontal rule is a line that contains only hyphens, underscores,
340
or asterisks, and optionally spaces. The length must be at least 3.
341
~~~
343
---------------
344
________
346
* * *
348
~~~
349
turns into
351
---------------
353
________
355
* * *
357
### Summary of blocks
359
1. **Void:** blank line, or line starting with `;`, empty and not output.
360
2. **Paragraph:** anything not recognised as another block, can contain
361
inline elements but not blocks.
362
3. **Heading:** prefix with `#` or underline, single-line, can contain
363
inline elements.
364
4. **Fence:** code block, starts and ends with `~~~` or `````,
365
can contain only text, optionally with a language descriptor.
366
5. **Blockquote:** starts with `>`, can contain other blocks with recursive
367
parsing.
368
6. **List:** starts with `*`, `+`, `-`, or `<number>.`, continuation lines
369
are indented with two spaces, can contain other blocks with recursive
370
parsing.
371
7. **Horizontal rule:** line with at least 3 characters, hyphens,
372
underscores, or asterisks, optionally with spaces.
373
Inline elements
375
---------------
376
### Text
378
Technically not an inline element, represented by a simple text in the
379
output. Anything not otherwise recognised is text.
380
### Emphasis
382
Emphasis is represented by `*` or `_` surrounding the text. When using `_`,
383
the emphasis must be surrounded by spaces or start/end of the line.
384
There can be at most 7 markers on each side, the number of opening markers
386
must be exactly the same as the number of closing markers,
387
and they cannot be mixed, unlike in standard markdown. (Maybe this will change
388
in the future, but we'll see.) However mixing them sometimes works, only when
389
nesting makes sense.
390
The number of markers is interpreted as a sum of powers of 2. If it's 4 or
392
more then there's the third level of emphasis, if the remainder is 2 or more
393
then there's the second level of emphasis, and if there's a remainder then
394
there's the first level of emphasis. You can see how they look below:
395
1. *level 1*
397
2. **level 2**
398
3. ***level 1+2***
399
4. ****level 3****
400
5. *****level 1+3*****
401
6. ******level 2+3******
402
7. *******level 1+2+3*******
403
### Strikethrough
405
Strikethrough is represented by `~~` surrounding the text.
406
### Diff marker
408
Diff markers are represented by `++` on either side of the text for inserted
409
text and `--` for deleted text.
410
### Link
412
Links are represented by `[text](url)`. The text can contain inline elements.
413
Title attributes are currently not supported, but they will be.
414
#### Image
416
Images are represented by ``.
417
### Code
419
Code is represented by ``` surrounding the text.
420
Using two backticks is not currently supported.
421
### Summary of inline elements
423
1. **Text:** anything not recognised as another inline element.
424
2. **Emphasis:** `*` or `_` surrounding the text, at most 7 markers on each side.
425
3. **Strikethrough:** `~~` surrounding the text.
426
4. **Diff marker:** `++` or `--` surrounding the text.
427
5. **Link:** `[text](url)`, text can contain inline elements.
428
6. **Image:** ``.
429
7. **Code:** ``` surrounding the text.
430